Project: use a choicefield for selecting the versioning scheme #10845
Conversation
There was a problem hiding this comment.
I thought a part of this project was adding a "single language / multiple version" concept, which makes this language a bit more important to consider. I'm not 100% sure what the right language here is, but seems like we might want to make that change in this PR as well?
readthedocs/projects/constants.py
Outdated
| MULTI_VERSION = "multi_version" | ||
| VERSIONING_SCHEME_CHOICES = ( | ||
| (SINGLE_VERSION, _("Single version")), | ||
| (MULTI_VERSION, _("Multi version")), |
There was a problem hiding this comment.
I worry about this language when we introduce Single language projects. It seems like we need a better way to describe these projects that takes into account translations as well?
There was a problem hiding this comment.
So, first I named these:
- Single version, single language
- Multi version, multi language
- Multi version, single language (the new option)
But it felt too verbose, and I was hoping that having the preview of each case would clarify things better.
Maybe just re-think this as:
- Single version without translations
- Multiple versions with translations
- Multiple versions without translations (the new option)
Still verbose, but maybe more clear for users that aren't familiar with our language.
There was a problem hiding this comment.
I think explicit is probably best to start, if there isn't an obvious other way to describe it. I think the main thing is actually explaining the URL path (eg. Multiple versions without translations (/<version>/<file>)
There was a problem hiding this comment.
Do you mean use a placeholder instead of a live preview? Right now I'm showing how the URL will look like for the project (/latest/file.html, /en/latest/file.html, /projects/en/latest, using their language, subproject prefix, etc)
There was a problem hiding this comment.
That is great -- I think a live prefix is the most useful way to understand this. On top of that, I think we can just use the explicit naming above,.
There was a problem hiding this comment.
IMHO, Multiple versions without translations (/<version>/<file>) with a static example is the best explanation. It may be verbose, but it removes all type of confusions.
Even if you don't know what's the meaning of /en/ in the URL, if you want to host documentation in different languages you will select the option that says "... with translations"
There was a problem hiding this comment.
I'm fine with both options, static or dynamic preview.
There was a problem hiding this comment.
I think static is better since it's more explicit and the user doesn't need to know what en is 👍
|
|
||
| SINGLE_VERSION_WITHOUT_TRANSLATIONS = "single_version_without_translations" | ||
| MULTIPLE_VERSIONS_WITH_TRANSLATIONS = "multiple_versions_with_translations" | ||
| VERSIONING_SCHEME_CHOICES = ( |
There was a problem hiding this comment.
This PR looks pretty much done to me, but we still don't have "Single version with translations" or similar in this list. I thought that was part of this PR?
There was a problem hiding this comment.
That's going to be added in #10766
|
Seems this is ready to merge -- would be good to get moving so we can get #10766 in as well 💯 |
|
@ericholscher any preference on #10845 (comment)? |
We may want to publish a small blog post communicating this change, when updating a project with API v3,
versioning_schemeshould be used instead ofsingle_version.This looks like this:
Closes #10781
How to deploy this change